home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / interp / perl-5.003.tar.gz / perl-5.003.tar / perl-5.003 / pod / perlmod.pod < prev    next >
Text File  |  1996-03-25  |  34KB  |  1,070 lines
  1. =head1 NAME
  2.  
  3. perlmod - Perl modules (packages)
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. =head2 Packages
  8.  
  9. Perl provides a mechanism for alternative namespaces to protect packages
  10. from stomping on each others variables.  In fact, apart from certain
  11. magical variables, there's really no such thing as a global variable in
  12. Perl.  The package statement declares the compilation unit as being in the
  13. given namespace.  The scope of the package declaration is from the
  14. declaration itself through the end of the enclosing block (the same scope
  15. as the local() operator).  All further unqualified dynamic identifiers
  16. will be in this namespace.  A package statement only affects dynamic
  17. variables--including those you've used local() on--but I<not> lexical
  18. variables created with my().  Typically it would be the first declaration
  19. in a file to be included by the C<require> or C<use> operator.  You can
  20. switch into a package in more than one place; it merely influences which
  21. symbol table is used by the compiler for the rest of that block.  You can
  22. refer to variables and filehandles in other packages by prefixing the
  23. identifier with the package name and a double colon:
  24. C<$Package::Variable>.  If the package name is null, the C<main> package
  25. as assumed.  That is, C<$::sail> is equivalent to C<$main::sail>.
  26.  
  27. (The old package delimiter was a single quote, but double colon
  28. is now the preferred delimiter, in part because it's more readable
  29. to humans, and in part because it's more readable to B<emacs> macros.
  30. It also makes C++ programmers feel like they know what's going on.)
  31.  
  32. Packages may be nested inside other packages: C<$OUTER::INNER::var>.  This
  33. implies nothing about the order of name lookups, however.  All symbols
  34. are either local to the current package, or must be fully qualified
  35. from the outer package name down.  For instance, there is nowhere
  36. within package C<OUTER> that C<$INNER::var> refers to C<$OUTER::INNER::var>.
  37. It would treat package C<INNER> as a totally separate global package.
  38.  
  39. Only identifiers starting with letters (or underscore) are stored in a
  40. package's symbol table.  All other symbols are kept in package C<main>,
  41. including all of the punctuation variables like $_.  In addition, the
  42. identifiers STDIN, STDOUT, STDERR, ARGV, ARGVOUT, ENV, INC and SIG are
  43. forced to be in package C<main>, even when used for other purposes than
  44. their built-in one.  Note also that, if you have a package called C<m>,
  45. C<s> or C<y>, then you can't use the qualified form of an identifier
  46. because it will be interpreted instead as a pattern match, a substitution,
  47. or a translation.
  48.  
  49. (Variables beginning with underscore used to be forced into package
  50. main, but we decided it was more useful for package writers to be able
  51. to use leading underscore to indicate private variables and method names.
  52. $_ is still global though.)
  53.  
  54. Eval()ed strings are compiled in the package in which the eval() was
  55. compiled.  (Assignments to C<$SIG{}>, however, assume the signal
  56. handler specified is in the C<main> package.  Qualify the signal handler
  57. name if you wish to have a signal handler in a package.)  For an
  58. example, examine F<perldb.pl> in the Perl library.  It initially switches
  59. to the C<DB> package so that the debugger doesn't interfere with variables
  60. in the script you are trying to debug.  At various points, however, it
  61. temporarily switches back to the C<main> package to evaluate various
  62. expressions in the context of the C<main> package (or wherever you came
  63. from).  See L<perldebug>.
  64.  
  65. See L<perlsub> for other scoping issues related to my() and local(), 
  66. or L<perlref> regarding closures.
  67.  
  68. =head2 Symbol Tables
  69.  
  70. The symbol table for a package happens to be stored in the associative
  71. array of that name appended with two colons.  The main symbol table's
  72. name is thus C<%main::>, or C<%::> for short.  Likewise the nested package
  73. mentioned earlier is named C<%OUTER::INNER::>.
  74.  
  75. The value in each entry of the associative array is what you are referring
  76. to when you use the C<*name> typeglob notation.  In fact, the following
  77. have the same effect, though the first is more efficient because it does
  78. the symbol table lookups at compile time:
  79.  
  80.     local(*main::foo) = *main::bar; local($main::{'foo'}) =
  81.     $main::{'bar'};
  82.  
  83. You can use this to print out all the variables in a package, for
  84. instance.  Here is F<dumpvar.pl> from the Perl library:
  85.  
  86.    package dumpvar;
  87.    sub main::dumpvar {
  88.        ($package) = @_;
  89.        local(*stab) = eval("*${package}::");
  90.        while (($key,$val) = each(%stab)) {
  91.        local(*entry) = $val;
  92.        if (defined $entry) {
  93.            print "\$$key = '$entry'\n";
  94.        }
  95.  
  96.        if (defined @entry) {
  97.            print "\@$key = (\n";
  98.            foreach $num ($[ .. $#entry) {
  99.            print "  $num\t'",$entry[$num],"'\n";
  100.            }
  101.            print ")\n";
  102.        }
  103.  
  104.        if ($key ne "${package}::" && defined %entry) {
  105.            print "\%$key = (\n";
  106.            foreach $key (sort keys(%entry)) {
  107.            print "  $key\t'",$entry{$key},"'\n";
  108.            }
  109.            print ")\n";
  110.        }
  111.        }
  112.    }
  113.  
  114. Note that even though the subroutine is compiled in package C<dumpvar>,
  115. the name of the subroutine is qualified so that its name is inserted
  116. into package C<main>.
  117.  
  118. Assignment to a typeglob performs an aliasing operation, i.e.,
  119.  
  120.     *dick = *richard;
  121.  
  122. causes variables, subroutines and file handles accessible via the
  123. identifier C<richard> to also be accessible via the symbol C<dick>.  If
  124. you only want to alias a particular variable or subroutine, you can
  125. assign a reference instead:
  126.  
  127.     *dick = \$richard;
  128.  
  129. makes $richard and $dick the same variable, but leaves
  130. @richard and @dick as separate arrays.  Tricky, eh?
  131.  
  132. This mechanism may be used to pass and return cheap references
  133. into or from subroutines if you won't want to copy the whole
  134. thing.
  135.  
  136.     %some_hash = ();
  137.     *some_hash = fn( \%another_hash );
  138.     sub fn {
  139.     local *hashsym = shift;
  140.     # now use %hashsym normally, and you
  141.     # will affect the caller's %another_hash
  142.     my %nhash = (); # do what you want
  143.     return \%nhash; 
  144.     }
  145.  
  146. On return, the reference wil overwrite the hash slot in the
  147. symbol table specified by the *some_hash typeglob.  This
  148. is a somewhat tricky way of passing around refernces cheaply
  149. when you won't want to have to remember to dereference variables
  150. explicitly.
  151.  
  152. Another use of symbol tables is for making "constant"  scalars.
  153.  
  154.     *PI = \3.14159265358979;
  155.  
  156. Now you cannot alter $PI, which is probably a good thing all in all.
  157.  
  158. =head2 Package Constructors and Destructors
  159.  
  160. There are two special subroutine definitions that function as package
  161. constructors and destructors.  These are the C<BEGIN> and C<END>
  162. routines.  The C<sub> is optional for these routines.
  163.  
  164. A C<BEGIN> subroutine is executed as soon as possible, that is, the
  165. moment it is completely defined, even before the rest of the containing
  166. file is parsed.  You may have multiple C<BEGIN> blocks within a
  167. file--they will execute in order of definition.  Because a C<BEGIN>
  168. block executes immediately, it can pull in definitions of subroutines
  169. and such from other files in time to be visible to the rest of the
  170. file.
  171.  
  172. An C<END> subroutine is executed as late as possible, that is, when the
  173. interpreter is being exited, even if it is exiting as a result of a
  174. die() function.  (But not if it's is being blown out of the water by a
  175. signal--you have to trap that yourself (if you can).)  You may have
  176. multiple C<END> blocks within a file--they will execute in reverse
  177. order of definition; that is: last in, first out (LIFO).
  178.  
  179. Note that when you use the B<-n> and B<-p> switches to Perl, C<BEGIN>
  180. and C<END> work just as they do in B<awk>, as a degenerate case.
  181.  
  182. =head2 Perl Classes
  183.  
  184. There is no special class syntax in Perl, but a package may function
  185. as a class if it provides subroutines that function as methods.  Such a
  186. package may also derive some of its methods from another class package
  187. by listing the other package name in its @ISA array.  
  188.  
  189. For more on this, see L<perlobj>.
  190.  
  191. =head2 Perl Modules
  192.  
  193. A module is just a package that is defined in a library file of
  194. the same name, and is designed to be reusable.  It may do this by
  195. providing a mechanism for exporting some of its symbols into the symbol
  196. table of any package using it.  Or it may function as a class
  197. definition and make its semantics available implicitly through method
  198. calls on the class and its objects, without explicit exportation of any
  199. symbols.  Or it can do a little of both.
  200.  
  201. For example, to start a normal module called Fred, create
  202. a file called Fred.pm and put this at the start of it:
  203.  
  204.     package      Fred;
  205.     require      Exporter;
  206.     @ISA       = qw(Exporter);
  207.     @EXPORT    = qw(func1 func2);
  208.     @EXPORT_OK = qw($sally @listabob %harry func3);
  209.  
  210. Then go on to declare and use your variables in functions
  211. without any qualifications.
  212. See L<Exporter> and the I<Perl Modules File> for details on 
  213. mechanics and style issues in module creation.
  214.  
  215. Perl modules are included into your program by saying
  216.  
  217.     use Module;
  218.  
  219. or
  220.  
  221.     use Module LIST;
  222.  
  223. This is exactly equivalent to
  224.  
  225.     BEGIN { require "Module.pm"; import Module; }
  226.  
  227. or
  228.  
  229.     BEGIN { require "Module.pm"; import Module LIST; }
  230.  
  231. As a special case
  232.  
  233.     use Module ();
  234.  
  235. is exactly equivalent to
  236.  
  237.     BEGIN { require "Module.pm"; }
  238.  
  239. All Perl module files have the extension F<.pm>.  C<use> assumes this so
  240. that you don't have to spell out "F<Module.pm>" in quotes.  This also
  241. helps to differentiate new modules from old F<.pl> and F<.ph> files.
  242. Module names are also capitalized unless they're functioning as pragmas,
  243. "Pragmas" are in effect compiler directives, and are sometimes called
  244. "pragmatic modules" (or even "pragmata" if you're a classicist).
  245.  
  246. Because the C<use> statement implies a C<BEGIN> block, the importation
  247. of semantics happens at the moment the C<use> statement is compiled,
  248. before the rest of the file is compiled.  This is how it is able
  249. to function as a pragma mechanism, and also how modules are able to
  250. declare subroutines that are then visible as list operators for
  251. the rest of the current file.  This will not work if you use C<require>
  252. instead of C<use>.  With require you can get into this problem:
  253.  
  254.     require Cwd;        # make Cwd:: accessible
  255.     $here = Cwd::getcwd();    
  256.  
  257.     use Cwd;            # import names from Cwd:: 
  258.     $here = getcwd();
  259.  
  260.     require Cwd;            # make Cwd:: accessible
  261.     $here = getcwd();         # oops! no main::getcwd()
  262.  
  263. In general C<use Module ();> is recommended over C<require Module;>.
  264.  
  265. Perl packages may be nested inside other package names, so we can have
  266. package names containing C<::>.  But if we used that package name
  267. directly as a filename it would makes for unwieldy or impossible
  268. filenames on some systems.  Therefore, if a module's name is, say,
  269. C<Text::Soundex>, then its definition is actually found in the library
  270. file F<Text/Soundex.pm>.
  271.  
  272. Perl modules always have a F<.pm> file, but there may also be dynamically
  273. linked executables or autoloaded subroutine definitions associated with
  274. the module.  If so, these will be entirely transparent to the user of
  275. the module.  It is the responsibility of the F<.pm> file to load (or
  276. arrange to autoload) any additional functionality.  The POSIX module
  277. happens to do both dynamic loading and autoloading, but the user can
  278. just say C<use POSIX> to get it all.
  279.  
  280. For more information on writing extension modules, see L<perlxs>
  281. and L<perlguts>.
  282.  
  283. =head1 NOTE
  284.  
  285. Perl does not enforce private and public parts of its modules as you may
  286. have been used to in other languages like C++, Ada, or Modula-17.  Perl
  287. doesn't have an infatuation with enforced privacy.  It would prefer
  288. that you stayed out of its living room because you weren't invited, not
  289. because it has a shotgun.
  290.  
  291. The module and its user have a contract, part of which is common law,
  292. and part of which is "written".  Part of the common law contract is
  293. that a module doesn't pollute any namespace it wasn't asked to.  The
  294. written contract for the module (AKA documentation) may make other
  295. provisions.  But then you know when you C<use RedefineTheWorld> that
  296. you're redefining the world and willing to take the consequences.
  297.  
  298. =head1 THE PERL MODULE LIBRARY
  299.  
  300. A number of modules are included the the Perl distribution.  These are
  301. described below, and all end in F<.pm>.  You may also discover files in 
  302. the library directory that end in either F<.pl> or F<.ph>.  These are old
  303. libraries supplied so that old programs that use them still run.  The
  304. F<.pl> files will all eventually be converted into standard modules, and
  305. the F<.ph> files made by B<h2ph> will probably end up as extension modules
  306. made by B<h2xs>.  (Some F<.ph> values may already be available through the
  307. POSIX module.)  The B<pl2pm> file in the distribution may help in your
  308. conversion, but it's just a mechanical process, so is far from bullet proof.
  309.  
  310. =head2 Pragmatic Modules
  311.  
  312. They work somewhat like pragmas in that they tend to affect the compilation of
  313. your program, and thus will usually only work well when used within a
  314. C<use>, or C<no>.  These are locally scoped, so an inner BLOCK
  315. may countermand any of these by saying
  316.  
  317.     no integer;
  318.     no strict 'refs';
  319.  
  320. which lasts until the end of that BLOCK.
  321.  
  322. The following programs are defined (and have their own documentation).
  323.  
  324. =over 12
  325.  
  326. =item diagnostics
  327.  
  328. Pragma to produce enhanced diagnostics
  329.  
  330. =item integer
  331.  
  332. Pragma to compute arithmetic in integer instead of double
  333.  
  334. =item less
  335.  
  336. Pragma to request less of something from the compiler
  337.  
  338. =item overload
  339.  
  340. Pragma for overloading operators 
  341.  
  342. =item sigtrap
  343.  
  344. Pragma to enable stack backtrace on unexpected signals
  345.  
  346. =item strict
  347.  
  348. Pragma to restrict unsafe constructs
  349.  
  350. =item subs
  351.  
  352. Pragma to predeclare sub names
  353.  
  354. =back
  355.  
  356. =head2 Standard Modules
  357.  
  358. Standard, bundled modules are all expected to behave in a well-defined
  359. manner with respect to namespace pollution because they use the
  360. Exporter module.  See their own documentation for details.
  361.  
  362. =over 12
  363.  
  364. =item AnyDBM_File
  365.  
  366. provide framework for multiple DBMs
  367.  
  368. =item AutoLoader
  369.  
  370. load functions only on demand
  371.  
  372. =item AutoSplit
  373.  
  374. split a package for autoloading
  375.  
  376. =item Benchmark
  377.  
  378. benchmark running times of code
  379.  
  380. =item Carp
  381.  
  382. warn of errors (from perspective of caller)
  383.  
  384. =item Config
  385.  
  386. access Perl configuration option
  387.  
  388. =item Cwd
  389.  
  390. get pathname of current working directory
  391.  
  392. =item DB_File
  393.  
  394. Perl access to Berkeley DB
  395.  
  396. =item Devel::SelfStubber
  397.  
  398. generate stubs for a SelfLoading module
  399.  
  400. =item DynaLoader
  401.  
  402. Dynamically load C libraries into Perl code
  403.  
  404. =item English
  405.  
  406. use nice English (or awk) names for ugly punctuation variables
  407.  
  408. =item Env
  409.  
  410. perl module that imports environment variables
  411.  
  412. =item Exporter
  413.  
  414. provide inport/export controls for Perl modules
  415.  
  416. =item ExtUtils::Liblist
  417.  
  418. determine libraries to use and how to use them
  419.  
  420. =item ExtUtils::MakeMaker
  421.  
  422. create an extension Makefile
  423.  
  424. =item ExtUtils::Manifest
  425.  
  426. utilities to write and check a MANIFEST file
  427.  
  428. =item ExtUtils::Mkbootstrap
  429.  
  430. make a bootstrap file for use by DynaLoader
  431.  
  432. =item ExtUtils::Miniperl
  433.  
  434. !!!GOOD QUESTION!!!
  435.  
  436. =item Fcntl
  437.  
  438. load the C Fcntl.h defines
  439.  
  440. =item File::Basename
  441.  
  442. parse file specifications
  443.  
  444. =item File::CheckTree
  445.  
  446. run many filetest checks on a tree
  447.  
  448. =item File::Find
  449.  
  450. traverse a file tree
  451.  
  452. =item FileHandle
  453.  
  454. supply object methods for filehandles
  455.  
  456. =item File::Path
  457.  
  458. create or remove a series of directories
  459.  
  460. =item Getopt::Long
  461.  
  462. extended getopt processing
  463.  
  464. =item Getopt::Std
  465.  
  466. Process single-character switches with switch clustering
  467.  
  468. =item I18N::Collate
  469.  
  470. compare 8-bit scalar data according to the current locale
  471.  
  472. =item IPC::Open2
  473.  
  474. a process for both reading and writing
  475.  
  476. =item IPC::Open3
  477.  
  478. open a process for reading, writing, and error handling
  479.  
  480. =item Net::Ping
  481.  
  482. check a host for upness
  483.  
  484. =item POSIX
  485.  
  486. Perl interface to IEEE Std 1003.1
  487.  
  488. =item SelfLoader
  489.  
  490. load functions only on demand
  491.  
  492. =item Safe
  493.  
  494. Creation controlled compartments in which perl code can be evaluated.
  495.  
  496. =item Socket
  497.  
  498. load the C socket.h defines and structure manipulators
  499.  
  500. =item Test::Harness
  501.  
  502. run perl standard test scripts with statistics
  503.  
  504. =item Text::Abbrev
  505.  
  506. rceate an abbreviation table from a list
  507.  
  508. =back
  509.  
  510. To find out I<all> the modules installed on your system, including
  511. those without documentation or outside the standard release, do this:
  512.  
  513.     find `perl -e 'print "@INC"'` -name '*.pm' -print
  514.  
  515. They should all have their own documentation installed and accessible via
  516. your system man(1) command.  If that fails, try the I<perldoc> program.
  517.  
  518. =head2 Extension Modules
  519.  
  520. Extension modules are written in C (or a mix of Perl and C) and get
  521. dynamically loaded into Perl if and when you need them.  Supported
  522. extension modules include the Socket, Fcntl, and POSIX modules.
  523.  
  524. Many popular C extension modules do not come bundled (at least, not
  525. completely) due to their size, volatility, or simply lack of time for
  526. adequate testing and configuration across the multitude of platforms on
  527. which Perl was beta-tested.  You are encouraged to look for them in
  528. archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
  529. authors before randomly posting asking for their present condition and
  530. disposition.
  531.  
  532. =head1 CPAN
  533.  
  534. CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
  535. replicated collection of all known Perl materials, including hundreds 
  536. of unbunded modules.  Here are the major categories of modules:
  537.  
  538. =over
  539.  
  540. =item *
  541. Language Extensions and Documentation Tools 
  542.  
  543. =item *
  544. Development Support
  545.  
  546. =item *
  547. Operating System Interfaces
  548.  
  549. =item *
  550. Networking, Device Control (modems) and InterProcess Communication
  551.  
  552. =item *
  553. Data Types and Data Type Utilities
  554.  
  555. =item *
  556. Database Interfaces
  557.  
  558. =item *
  559. User Interfaces
  560.  
  561. =item *
  562. Interfaces to / Emulations of Other Programming Languages
  563.  
  564. =item *
  565. File Names, File Systems and File Locking (see also File Handles)
  566.  
  567. =item *
  568. String Processing, Language Text Processing, Parsing and Searching
  569.  
  570. =item *
  571. Option, Argument, Parameter and Configuration File Processing
  572.  
  573. =item *
  574. Internationalization and Locale
  575.  
  576. =item *
  577. Authentication, Security and Encryption
  578.  
  579. =item *
  580. World Wide Web, HTML, HTTP, CGI, MIME
  581.  
  582. =item *
  583. Server and Daemon Utilities
  584.  
  585. =item *
  586. Archiving and Compression
  587.  
  588. =item *
  589. Images, Pixmap and Bitmap Manipulation, Drawing and Graphing
  590.  
  591. =item *
  592. Mail and Usenet News
  593.  
  594. =item *
  595. Control Flow Utilities (callbacks and exceptions etc)
  596.  
  597. =item *
  598. File Handle and Input/Output Stream Utilities
  599.  
  600. =item *
  601. Miscellaneous Modules
  602.  
  603. =back
  604.  
  605. Some of the reguster CPAN sites as of this writing include the following.
  606. You should try to choose one close to you:
  607.  
  608. =over
  609.  
  610. =item *
  611. ftp://ftp.sterling.com/programming/languages/perl/
  612.  
  613. =item *
  614. ftp://ftp.sedl.org/pub/mirrors/CPAN/
  615.  
  616. =item *
  617. ftp://ftp.uoknor.edu/mirrors/CPAN/
  618.  
  619. =item *
  620. ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
  621.  
  622. =item *
  623. ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
  624.  
  625. =item *
  626. ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
  627.  
  628. =item *
  629. ftp://ftp.switch.ch/mirror/CPAN/
  630.  
  631. =item *
  632. ftp://ftp.sunet.se/pub/lang/perl/CPAN/
  633.  
  634. =item *
  635. ftp://ftp.ci.uminho.pt/pub/lang/perl/
  636.  
  637. =item *
  638. ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
  639.  
  640. =item *
  641. ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
  642.  
  643. =item *
  644. ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
  645.  
  646. =item *
  647. ftp://ftp.leo.org/pub/comp/programming/languages/perl/CPAN/
  648.  
  649. =item *
  650. ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
  651.  
  652. =item *
  653. ftp://ftp.ibp.fr/pub/perl/CPAN/
  654.  
  655. =item *
  656. ftp://ftp.funet.fi/pub/languages/perl/CPAN/
  657.  
  658. =item *
  659. ftp://ftp.tekotago.ac.nz/pub/perl/CPAN/
  660.  
  661. =item *
  662. ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/
  663.  
  664. =item *
  665. ftp://coombs.anu.edu.au/pub/perl/
  666.  
  667. =item *
  668. ftp://dongpo.math.ncu.edu.tw/perl/CPAN/
  669.  
  670. =item *
  671. ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
  672.  
  673. =item *
  674. ftp://ftp.is.co.za/programming/perl/CPAN/
  675.  
  676. =back
  677.  
  678. For an up-to-date listing of CPAN sites, 
  679. see http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .
  680.  
  681. =head1 Modules: Creation, Use and Abuse
  682.  
  683. (The following section is borrowed directly from Tim Bunce's modules
  684. file, available at your nearest CPAN site.)
  685.  
  686. Perl 5 implements a class using a package, but the presence of a
  687. package doesn't imply the presence of a class.  A package is just a
  688. namespace.  A class is a package that provides subroutines that can be
  689. used as methods.  A method is just a subroutine that expects, as its
  690. first argument, either the name of a package (for "static" methods),
  691. or a reference to something (for "virtual" methods).
  692.  
  693. A module is a file that (by convention) provides a class of the same
  694. name (sans the .pm), plus an import method in that class that can be
  695. called to fetch exported symbols.  This module may implement some of
  696. its methods by loading dynamic C or C++ objects, but that should be
  697. totally transparent to the user of the module.  Likewise, the module
  698. might set up an AUTOLOAD function to slurp in subroutine definitions on
  699. demand, but this is also transparent.  Only the .pm file is required to
  700. exist.
  701.  
  702. =head2 Guidelines for Module Creation
  703.  
  704. =over 4
  705.  
  706. =item Do similar modules already exist in some form?
  707.  
  708. If so, please try to reuse the existing modules either in whole or
  709. by inheriting useful features into a new class.  If this is not
  710. practical try to get together with the module authors to work on
  711. extending or enhancing the functionality of the existing modules.
  712. A perfect example is the plethora of packages in perl4 for dealing
  713. with command line options.
  714.  
  715. If you are writing a module to expand an already existing set of
  716. modules, please coordinate with the author of the package.  It
  717. helps if you follow the same naming scheme and module interaction
  718. scheme as the original author.
  719.  
  720. =item Try to design the new module to be easy to extend and reuse.
  721.  
  722. Use blessed references.  Use the two argument form of bless to bless
  723. into the class name given as the first parameter of the constructor,
  724. e.g.:
  725.  
  726.  sub new { 
  727.     my $class = shift;
  728.     return bless {}, $class;
  729.  }
  730.  
  731. or even this if you'd like it to be used as either a static
  732. or a virtual method.
  733.  
  734.  sub new { 
  735.     my $self  = shift;
  736.     my $class = ref($self) || $self;
  737.     return bless {}, $class;
  738.  }
  739.  
  740. Pass arrays as references so more parameters can be added later
  741. (it's also faster).  Convert functions into methods where
  742. appropriate.  Split large methods into smaller more flexible ones.
  743. Inherit methods from other modules if appropriate.
  744.  
  745. Avoid class name tests like: die "Invalid" unless ref $ref eq 'FOO'.
  746. Generally you can delete the "eq 'FOO'" part with no harm at all.
  747. Let the objects look after themselves! Generally, avoid hardwired
  748. class names as far as possible.
  749.  
  750. Avoid $r-E<gt>Class::func() where using @ISA=qw(... Class ...) and
  751. $r-E<gt>func() would work (see perlbot man page for more details).
  752.  
  753. Use autosplit so little used or newly added functions won't be a
  754. burden to programs which don't use them. Add test functions to
  755. the module after __END__ either using AutoSplit or by saying:
  756.  
  757.  eval join('',<main::DATA>) || die $@ unless caller();
  758.  
  759. Does your module pass the 'empty sub-class' test? If you say
  760. "@SUBCLASS::ISA = qw(YOURCLASS);" your applications should be able
  761. to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
  762. does your application still work if you change:  $obj = new YOURCLASS;
  763. into: $obj = new SUBCLASS; ?
  764.  
  765. Avoid keeping any state information in your packages. It makes it
  766. difficult for multiple other packages to use yours. Keep state
  767. information in objects.
  768.  
  769. Always use C<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
  770. Remember that you can add C<no strict qw(...);> to individual blocks
  771. of code which need less strictness. Always use C<-w>. Always use C<-w>!
  772. Follow the guidelines in the perlstyle(1) manual.
  773.  
  774. =item Some simple style guidelines
  775.  
  776. The perlstyle manual supplied with perl has many helpful points.
  777.  
  778. Coding style is a matter of personal taste. Many people evolve their
  779. style over several years as they learn what helps them write and
  780. maintain good code.  Here's one set of assorted suggestions that
  781. seem to be widely used by experienced developers:
  782.  
  783. Use underscores to separate words.  It is generally easier to read
  784. $var_names_like_this than $VarNamesLikeThis, especially for
  785. non-native speakers of English. It's also a simple rule that works
  786. consistently with VAR_NAMES_LIKE_THIS.
  787.  
  788. Package/Module names are an exception to this rule. Perl informally
  789. reserves lowercase module names for 'pragma' modules like integer
  790. and strict. Other modules normally begin with a capital letter and
  791. use mixed case with no underscores (need to be short and portable).
  792.  
  793. You may find it helpful to use letter case to indicate the scope
  794. or nature of a variable. For example:
  795.  
  796.  $ALL_CAPS_HERE   constants only (beware clashes with perl vars)
  797.  $Some_Caps_Here  package-wide global/static
  798.  $no_caps_here    function scope my() or local() variables
  799.  
  800. Function and method names seem to work best as all lowercase.
  801. E.g., $obj-E<gt>as_string().
  802.  
  803. You can use a leading underscore to indicate that a variable or
  804. function should not be used outside the package that defined it.
  805.  
  806. =item Select what to export.
  807.  
  808. Do NOT export method names!
  809.  
  810. Do NOT export anything else by default without a good reason!
  811.  
  812. Exports pollute the namespace of the module user.  If you must
  813. export try to use @EXPORT_OK in preference to @EXPORT and avoid
  814. short or common names to reduce the risk of name clashes.
  815.  
  816. Generally anything not exported is still accessible from outside the
  817. module using the ModuleName::item_name (or $blessed_ref-E<gt>method)
  818. syntax.  By convention you can use a leading underscore on names to
  819. informally indicate that they are 'internal' and not for public use.
  820.  
  821. (It is actually possible to get private functions by saying:
  822. my $subref = sub { ... };  &$subref; But there's no way to call that
  823. directly as a method, since a method must have a name in the symbol
  824. table.)
  825.  
  826. As a general rule, if the module is trying to be object oriented
  827. then export nothing. If it's just a collection of functions then
  828. @EXPORT_OK anything but use @EXPORT with caution.
  829.  
  830. =item Select a name for the module.
  831.  
  832. This name should be as descriptive, accurate and complete as
  833. possible.  Avoid any risk of ambiguity. Always try to use two or
  834. more whole words.  Generally the name should reflect what is special
  835. about what the module does rather than how it does it.  Please use
  836. nested module names to informally group or categorise a module.
  837. A module should have a very good reason not to have a nested name.
  838. Module names should begin with a capital letter.
  839.  
  840. Having 57 modules all called Sort will not make life easy for anyone
  841. (though having 23 called Sort::Quick is only marginally better :-).
  842. Imagine someone trying to install your module alongside many others.
  843. If in any doubt ask for suggestions in comp.lang.perl.misc.
  844.  
  845. If you are developing a suite of related modules/classes it's good
  846. practice to use nested classes with a common prefix as this will
  847. avoid namespace clashes. For example:  Xyz::Control, Xyz::View,
  848. Xyz::Model etc. Use the modules in this list as a naming guide.
  849.  
  850. If adding a new module to a set, follow the original author's
  851. standards for naming modules and the interface to methods in
  852. those modules.
  853.  
  854. To be portable each component of a module name should be limited to
  855. 11 characters. If it might be used on DOS then try to ensure each is
  856. unique in the first 8 characters. Nested modules make this easier.
  857.  
  858. =item Have you got it right?
  859.  
  860. How do you know that you've made the right decisions? Have you
  861. picked an interface design that will cause problems later? Have
  862. you picked the most appropriate name? Do you have any questions?
  863.  
  864. The best way to know for sure, and pick up many helpful suggestions,
  865. is to ask someone who knows. Comp.lang.perl.misc is read by just about
  866. all the people who develop modules and it's the best place to ask.
  867.  
  868. All you need to do is post a short summary of the module, its
  869. purpose and interfaces. A few lines on each of the main methods is
  870. probably enough. (If you post the whole module it might be ignored
  871. by busy people - generally the very people you want to read it!)
  872.  
  873. Don't worry about posting if you can't say when the module will be
  874. ready - just say so in the message. It might be worth inviting
  875. others to help you, they may be able to complete it for you!
  876.  
  877. =item README and other Additional Files.
  878.  
  879. It's well known that software developers usually fully document the
  880. software they write. If, however, the world is in urgent need of
  881. your software and there is not enough time to write the full
  882. documentation please at least provide a README file containing:
  883.  
  884. =over 10
  885.  
  886. =item *
  887. A description of the module/package/extension etc.
  888.  
  889. =item *
  890. A copyright notice - see below.
  891.  
  892. =item *
  893. Prerequisites - what else you may need to have.
  894.  
  895. =item *
  896. How to build it - possible changes to Makefile.PL etc.
  897.  
  898. =item *
  899. How to install it.
  900.  
  901. =item *
  902. Recent changes in this release, especially incompatibilities
  903.  
  904. =item *
  905. Changes / enhancements you plan to make in the future.
  906.  
  907. =back
  908.  
  909. If the README file seems to be getting too large you may wish to
  910. split out some of the sections into separate files: INSTALL,
  911. Copying, ToDo etc.
  912.  
  913. =item Adding a Copyright Notice.
  914.  
  915. How you choose to licence your work is a personal decision.
  916. The general mechanism is to assert your Copyright and then make
  917. a declaration of how others may copy/use/modify your work.
  918.  
  919. Perl, for example, is supplied with two types of licence: The GNU
  920. GPL and The Artistic License (see the files README, Copying and
  921. Artistic).  Larry has good reasons for NOT just using the GNU GPL.
  922.  
  923. My personal recommendation, out of respect for Larry, Perl and the
  924. perl community at large is to simply state something like:
  925.  
  926.  Copyright (c) 1995 Your Name. All rights reserved.
  927.  This program is free software; you can redistribute it and/or
  928.  modify it under the same terms as Perl itself.
  929.  
  930. This statement should at least appear in the README file. You may
  931. also wish to include it in a Copying file and your source files.
  932. Remember to include the other words in addition to the Copyright.
  933.  
  934. =item Give the module a version/issue/release number.
  935.  
  936. To be fully compatible with the Exporter and MakeMaker modules you
  937. should store your module's version number in a non-my package
  938. variable called $VERSION.  This should be a valid floating point 
  939. number with at least two digits after the decimal (ie hundredths,
  940. e.g, $VERSION = "0.01").  Don't use a "1.3.2" style version.
  941. See Exporter.pm in Perl5.001m or later for details.
  942.  
  943. It may be handy to add a function or method to retrieve the number.
  944. Use the number in announcements and archive file names when
  945. releasing the module (ModuleName-1.02.tar.Z).
  946. See perldoc ExtUtils::MakeMaker.pm for details.
  947.  
  948. =item How to release and distribute a module.
  949.  
  950. It's good idea to post an announcement of the availability of your
  951. module (or the module itself if small) to the comp.lang.perl.announce
  952. Usenet newsgroup.  This will at least ensure very wide once-off
  953. distribution.
  954.  
  955. If possible you should place the module into a major ftp archive and
  956. include details of it's location in your announcement.
  957.  
  958. Some notes about ftp archives: Please use a long descriptive file
  959. name which includes the version number. Most incoming directories
  960. will not be readable/listable, i.e., you won't be able to see your
  961. file after uploading it. Remember to send your email notification
  962. message as soon as possible after uploading else your file may get
  963. deleted automatically. Allow time for the file to be processed
  964. and/or check the file has been processed before announcing its
  965. location.
  966.  
  967. FTP Archives for Perl Modules:
  968.  
  969. Follow the instructions and links on
  970.  
  971.    http://franz.ww.tu-berlin.de/modulelist
  972.  
  973. or upload to one of these sites: 
  974.  
  975.    ftp://franz.ww.tu-berlin.de/incoming
  976.    ftp://ftp.cis.ufl.edu/incoming  
  977.  
  978. and notify upload@franz.ww.tu-berlin.de.
  979.  
  980. By using the WWW interface you can ask the Upload Server to mirror
  981. your modules from your ftp or WWW site into your own directory on
  982. CPAN!
  983.  
  984. Please remember to send me an updated entry for the Module list!
  985.  
  986. =item Take care when changing a released module.
  987.  
  988. Always strive to remain compatible with previous released versions
  989. (see 2.2 above) Otherwise try to add a mechanism to revert to the
  990. old behaviour if people rely on it. Document incompatible changes.
  991.  
  992. =back
  993.  
  994. =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
  995.  
  996. =over 4
  997.  
  998. =item There is no requirement to convert anything.
  999.  
  1000. If it ain't broke, don't fix it! Perl 4 library scripts should
  1001. continue to work with no problems. You may need to make some minor
  1002. changes (like escaping non-array @'s in double quoted strings) but
  1003. there is no need to convert a .pl file into a Module for just that.
  1004.  
  1005. =item Consider the implications.
  1006.  
  1007. All the perl applications which make use of the script will need to
  1008. be changed (slightly) if the script is converted into a module.  Is
  1009. it worth it unless you plan to make other changes at the same time?
  1010.  
  1011. =item Make the most of the opportunity.
  1012.  
  1013. If you are going to convert the script to a module you can use the
  1014. opportunity to redesign the interface. The 'Guidelines for Module
  1015. Creation' above include many of the issues you should consider.
  1016.  
  1017. =item The pl2pm utility will get you started.
  1018.  
  1019. This utility will read *.pl files (given as parameters) and write
  1020. corresponding *.pm files. The pl2pm utilities does the following:
  1021.  
  1022. =over 10
  1023.  
  1024. =item *
  1025. Adds the standard Module prologue lines
  1026.  
  1027. =item *
  1028. Converts package specifiers from ' to ::
  1029.  
  1030. =item *
  1031. Converts die(...) to croak(...)
  1032.  
  1033. =item *
  1034. Several other minor changes
  1035.  
  1036. =back
  1037.  
  1038. Being a mechanical process pl2pm is not bullet proof. The converted
  1039. code will need careful checking, especially any package statements.
  1040. Don't delete the original .pl file till the new .pm one works!
  1041.  
  1042. =back
  1043.  
  1044. =head2 Guidelines for Reusing Application Code
  1045.  
  1046. =over 4
  1047.  
  1048. =item Complete applications rarely belong in the Perl Module Library.
  1049.  
  1050. =item Many applications contain some perl code which could be reused.
  1051.  
  1052. Help save the world! Share your code in a form that makes it easy
  1053. to reuse.
  1054.  
  1055. =item Break-out the reusable code into one or more separate module files.
  1056.  
  1057. =item Take the opportunity to reconsider and redesign the interfaces.
  1058.  
  1059. =item In some cases the 'application' can then be reduced to a small
  1060.  
  1061. fragment of code built on top of the reusable modules. In these cases
  1062. the application could invoked as:
  1063.  
  1064.      perl -e 'use Module::Name; method(@ARGV)' ...
  1065. or   
  1066.      perl -mModule::Name ...    (in perl5.002?)
  1067.  
  1068. =back
  1069.  
  1070.